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Revision History 


March 10,1986 

Ver. 0.11 

R. Montague 

Initial release. (no® thH this toolset wts seated from the 

Text, Basic aid Pascal functions previously implemented in the 
Miscellaneous Tools). 

March 31,1986 

Ver. 0.12 

R. Mcmtagne 

THIS IS A MAJOR REVISION!!! 

The text tool set has been redefined in order to make the tool set more 
usable. One call type supports BASIC PASCAL and RAM based 
drivers. Global psameters have changed. READ IT ALL!!! 

This will be implemented in the BETA 2.0 ROMS!!! 

April 3, 1986 

Ver. 0.13 

R. Mootagns 

Added Error Device Global Masks aid get I/O directing information. 

April 23, 1986 

Ver. 0.14 

R. Montague 

Changed eofieassuitkm of charactss in Wriine for RAM based drivers 
only. THIS IS THE BETA 2.0 IMPLEMENTATION. 

May 18,1986 

Ver. 0.15 

R. Montague 

Corrected esrors in GetOtrtGlofaals <& GctBrGlobals. Added note in 
Directing I/O functions with regard to Apple][ I/O hooks (italics). 

May 27, 1986 

Ver. 0.16 

R. Montagna 

Added a section on writing Ram Based Drives. 

June 26, 1986 

Ver. 0.17 

R. Moatagne 

No functional change, just added examples. 
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Text Tools. The text tool set provides an interface between Apple][ character device drivers 
which must be executed in emulation mode, and new applications running in native mode. It also 
provides a means of redirection of I/O through ram based drivers. The Text Tools (Tool set 
number - $0C) make it possible to deal with the text screen without switching modes and moving 
to bank zero. Dispatches to Ram based drivers will occur in full native mode (16 bit'm' and x'). 

Standard Tool Set Calls. 

TextBootMt Function number » $01 

This function sets up the default device parameters as follows: 

1. Input device type is BASIC 

2. Output device type is BASIC 

3. Error output device type is BASIC 

4. Input device resides in slot #3 

5. Output device resides in slot #3 

6. Error output device resides in slot #3 

7. Global input AND mask is set to $FF 

8. Global input OR mask is set to $80 

9. Global output AND mask is set to $FF 

10. Global output OR mask is set to $80 

11. Global error output AND mask is set to $FF 

12. Global error output OR mask is set to $80 

Example: 

TEXTBOOnNIT 


TextS tartUp Function number » $02 

This does nothing. 

Example: 

JTEXTSTARTUP 

TextShutDown Function number * $03 
This does nothing. 

Example: 

TEXTSHUTDOWN 
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TextVersion 

Function number = $04 

Input 

Word 

Space for result 

Output 

SP”> 

Word 

Version number 


This tool returns Ac version numbo* of the Text Tool Set 
Example: 

PEA $0000 ; SPACE FOR RESULT 

TextVersion 


TextReset Function number - SOS 


This function sets up the default device parameters as follows: 


1 . 

Input device type is BASIC 

2. 

Output device type is BASIC 

3. 

Error output device type is BASIC 

4. 

Input device resides in slot #3 

5. 

Output device resides in slot #3 

6. 

Error output device resides in slot #3 

7. 

Global input AND mask is set to $FF 

8. 

Global input OR mask is set to $80 

9. 

Global output AND mask is set to $FF 

10. 

Global output OR mask is set to $80 

11. 

Global error output AND mask is set to $FF 

12. 

Global error output OR mask is set to $80 

Example: 



JTEXTRESET 

Texts tatus 

Function number - $06 

Input 

Word Space for result 

sp™»> 


Output 

Word Status ($0000*>lnaetive, $FFFF=Active) 

sp—> 



This tool returns a status that indicates that the Text Tool Set is active. 


Example: 

PEA $0000 ; SPACE FOR RESULT 

JTEXTSTATUS 
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TextSparel Function number = $07 

This does nothing. 

Example*. 

JTEXTSPARE1 

TextSpare2 Function number * $08 

This does nothing. 

Example: 

TEXTSPARE2 
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Text Global Functions. These tools are used to set or read the current global 
parameters used by the Pascal and Basie text tools. Characters are logically 
ANDed with the AND mask, and then logically ORed with the OR mask by the 
Pascal and Basic text tools. 


SetlnGlobals Function number « $09 

Input Word AND mask 

Input Word OR mask 

sp—> 

Sets the global parameters for the input device. 

Example: 

PEA I00FF ; AND MASK 

PEA $0010 ; OR MASK 

SETINGLOBALS 


SetOutGlobals Function number ■ $0A 

Input Word AND mask 

Input Word OR mask 

sp—> 

Sets the global parameters for the output device. 

Example: 

PEA $00FF ; AND MASK 

PEA $0080 ; OR MASK 

SETOUTGLOBALS 


SetEnGlobals Function number ® SOB 

Input Word AND mask 

Input Word OR mask 

sp—> 

Sets the global parameters for the error output device. 
Example: 

PEA $00FF ; AND MASK 

PEA $0080 ; OR MASK 

SETERRGLOBALS 
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GednGlobals Function number = $0C 


Input 

Word 

Space for result 

Input 

Word 

Space for result 

Output 

Word 

AND mask 

Output 

Word 

OR mask 


sp—-> 


Returns with the current values for the input device global parameters. 
Example: 

FEA $0000 ; SPACE FOR RESULT 

PEA $0000 ; SPACE FOR RESULT 

GEHNGLOBALS 


GetOutGlobals Function number « SOD 


Input 

Word 

Space for result 

Input 

Word 

Space for mult 

Output 

Word 

AND mask 

Output 

Word 

OR mask 


sp-“> 


Returns with the current values for the Output device global parameters. 
Example: 

FEA $0000 ; SPACE FOR RESULT 

PEA $0000 ; SPACE FOR RESULT 

GETOUTGLOBALS 


GetEnGlobals Function number » $0E 


Input 

Word 

Space for result 

Input 

Word 

Space for mult 

S p— > 



Output 

Word 

AND mask 

Output 

sp— > 

Word 

OR mask 


Returns with the current values for the Error Output device global 
parameters. 

Example: 

PEA $0000 ; SPACE FOR RESULT 

PEA $0000 ; SPACE FOR RESULT 

GETERRGLOBALS 
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Directing I/O Functions. These tool functions are provided to direct I/O from 
the Text Tool Set to a specific type of character device driver or inquire 
information about the directing of a specific I/O driver. Three types of character 
device drivers are supported. 

DedsfiJEffifi Deoe£J2gadptian 

0 BASIC Device Driver 

1 PASCAL Device Driver 

2 RAM Based Device Drive* 

^3 _ Illegal Drive' Type 

BASIC device drivers must support the standard Apple][ BASIC device driver 
entry points (INTT, INPUT, and OUTPUT). It should he noted that the BASIC 
devices use the Apple]l HO hooks ($36~$39). Any desk accessories using the text 
tool set BASIC device drivers should save and restore the global masks, device 
descriptors and the I/O hooks when entering and exiting the DA. 

PASCAL device drivers must support the standard Apple][ Pascal 1.1 device 
drive entry points (3NTT, READ, WRITE, and status). The optional Pascal 1.1 
conffol entry point is supported by the text tool set, but does not neeeessarily have 
to be supported by the device. Dispatches to optional Pascal drive entry points 
that are not supported by the device will return a NO DEVICE CONNECTED 
error. 

RAM based device driven must support five entry points. These are 1NIT, 
READ, WRITE, STATUS and CONTROL. Ram bared driven may be located at 
any address and in any bank. Entry points must be supported by the RAM based 
drive as follows: 


RAMDRIVER Bare Address 
RAMDRIVER Bare Address+3 
RAMDRIVER Bare Address+6 
RAMDRIVER Bare Address+9 
RAMDRIVER Bare Address* 12 

(See section on writing ram base 


Initialization entry point 
Read entry point 
Write entty point 
Status enffy point 
Control enffy point 

more detail) 
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The text tool functions profided for directing the I/O to or from a specific device 
driver follows: 

SetXnputBeviee Function number = $QF 

Input Word Device Type 

Input Long Word Pointer or Slot 

Sp®“> 


The device type specifies the type of driver installed as the input device. 
The longword pointer points to die slot containing the device driver in the 
case of die device type being either a BASIC or PASCAL device driver. If 
the device type is a RAM based device driver, then the longword pointer 
points to die INITI ALIZA TION entry print within the RAM based driver. 

Example: 

PEA $0000 ; 0 » BASIC DRIVER 

PEA $0000 ; SLOT #3 

PEA $0003 

SEnNFUTDEVICE 


SetOutputDevice Function number ■ $10 

Input Word Device Type 

Input LongWord Pointer or Slot 

sp—> 


The device type specifies the type of driver installed as the output device. 
The longword pointer points to the slot containing the device driver in the 
case of the device type being either a BASIC or PASCAL device driver. If 
the device type is a RAM based device driver, then the longword pointer 
points to the INITTALEATION entry point within the RAM based driver. 

Example: 

PEA $0000 ; 2 » RAM BASED DRIVER 

PUSHLONG #LABEL ; BUFFER ADDRESS 

SETOUTPUTDEVICE 
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SetErrorDevice Function number ~ $11 


Input Word Device Type 

Input LongWord Pointer or Slot 

sp—> 


The device type specifies the type of driver installed as the error output 
device. The longword pointer points to the slot containing the device driver 
in the case of the device type being either a BASIC or PASCAL device 
driver. If the device type is a RAM based device driver, then the longword 
pointer points to the INITIALIZATION entry point within the RAM based 
driver. 

Example: 

PEA $0000 ; 1® PASCAL DRIVER 

PEA $0000 ; SLOT #3 

PEA $0003 

SETERRDEVICE 


GetlnputDeviee Function number » $12 


sp-—> 


sp—> 


Input 

Word 

Space for result 

Input 

Long Word 

Space for result 

Output 

Word 

Device Type 

Output 

Long Word 

Pointer or Slot 


The device type returned specifies the type of driver installed as the input 
device. The longword pointer points to the slot containing the device driver 
in the case of the device type being either a BASIC or PASCAL device 
driver. If the device type is a RAM based device driver, then the longword 
pointer points to the INITIALIZATION entry point within the RAM based 
driver. 

Example: 

PEA $0000 ; SPACE FOR TYPE 

PEA $0000 ; SPACE FOR LOCATION 

PEA $0000 

GEUNPUTDEVICE 
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sp—> 


Input 

Word 

Space for result 

Input 

LongWord 

Space for result 

Output 

Word 

Device Type 

Output 

LongWwd 

Pointer or Slot 


sp—> 


The device type returned specifies the type of driver installed as the output 
device. Hie longword pointer points to the slot containing the device driver 
in the case of the device type being either a BASIC or PASCAL device 
driver. If the device type is a RAM based device driver, then the longword 
pointer points to the INITIALIZATION entry point within the RAM based 
driver. 


sp—> 


Example: 

PEA 

$0000 


PEA 

$0000 


PEA 

$0000 


jGETOUTFUTDEVICE 

tot Device 

Function number * $14 

Input 

Word 

Space for result 

Input 

LongWord 

Space for result 

Output 

Word 

Device Type 

Output 

LongWord 

Pointer or Slot 


; SPACE FOR TYPE 
; SPACE FOR LOCATION 


sp*—> 


Hie device type specifies the type of driver installed as the error output 
device. The longword pointer points to the slot containing the device driver 
in the case of the device type being cither a BASIC or PASCAL device 
driver. If the device type is a RAM based device driver, then the longword 
pointer points to the INITIALIZATION entry point within the RAM based 
driver. 

Example: 

PEA $0000 ; SPACE FOR TYPE 

PEA $0000 ; SPACE FOR LOCATION 

PEA $0000 

GETERRORDEVICE 
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Text Functions. The tools specified below are provided to interface with any BASIC, 
PASCAL 1.1, or RAM based character device driver. Included are tool functions for initialization, 
control, input, output and status. 


InitTextDev Function number » $ 15 

Input Word Device to initialize 

sp—»> 


Initializes the text device specified by the tool input parameters as follows: 


Parameter 

0 

1 

2 

£3 


Device 
Input Device 
Output Device 
Enor Output Device 
Illegal parameter value 


Example: 

PEA $0000 ; INIT INPUT DEVICE 

INITTEXTDEV 


CiriTextDev 

Input 

Input 

sp—> 


Function number ® $16 

Word Device to control 

Word Control code (in low byte) 


Passes the control code to the text device specified by the tool input 
parameters. 


torna Dads 

0 Input Device 

1 Output Device 

2 Enor Output Device 

S3 Illegal parameter value 

Basic devices do not support this function. The text tool will return an enor 
if this can is made to a basic device. Note that for PASCAL device drivers, 
this is an optional entry point and may not be supported by all Pascal 
devices. 

Example: 

PEA $0001 ; CONTROL OUTPUT DEV 

PEA $0011 ; CONTROL CODE >$11 

CTRLTOCTDEV 
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StatusTDev Function number * $17 


Input Word Device to request status from 

Input Word Request code (in low byte) 

sp—> 


Executes a status call to the text device specified by the tool input 
parameters. 


Example: 


WriteChar 

Input 

sp=“> 


Parameter 

Device 

0 

Input Device 

1 

Output Device 

2 

Error Output Device 

£3 

Illegal parameter value 

PEA 

$0000 ; GET INPUT DEV STAT 

PEA 

$0010 ; REQUEST CODE - $10 

STATUSTEXTDEV 

BCS 

DEVNOTRDY ; BRANCH IF NOT READY 

Function number ® $18 

Word 

Character (in low byte of word) 


The character is combined with the output global AND mask and OR mask, 
and then is written to the text device specified by the output device. 


Example: 

PEA S003F ; OUTPUT A '? 

WRITECHAR 


EnWriteChar Function number ^ $19 

Input Word Character (in low byte of word) 

sp—> 


The character is combined with the error output global AND mask and OR 
mask, and then is written to the text device specified by the error output 
_ device. 

Example: 

PEA S003D ; OUTPUT A '=' 

ERRWRTTECHAR 
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WriteLine Function number - $ 1A 

Input Long Word Pointer to ASCII string 

sp—> 


Hie character string with a length specified by the first byte in the string is 
combined with the ouput global masks, and is then written to the text device 
specified as the output device. For BASIC and RAM based drivers, a 
carnage retom will be concatenated to the string by the tool. For PASCAL 
drivers, a carriage return and line feed will be concatenated to the steing by 
the tool. 

Example: 

PUSHLONG #LABEL ; BUFFER ADDRESS 
WRITELINE 


ErrWriteLine Function number - $1B 

Input Long Word Pointer to ASCII string 

sp—> 

The character string with a length specified by the first byte in the string is 
combined with the error ouput global masks, and is then written to the text 
device specified as the error output device. For BASIC and RAM based 
drivers, a carriage return will be concatenated to the string by the tooL For 
PASCAL drivers, a carriage return and line feed will be concatenated to the 
string by the tool. 

Example: 

PUSHLONG . #LABEL ; BUFFER ADDRESS 
ERRWRITELINE 


WriteS teing Function number ■ $1C 

Input Long Word Pointer to ASCII string 

sp—> 

The character string with a length specified by the first byte in the string is 
combined with the output global masks, and is then written to the text 
device specified as the output device. 

Example: 

PUSHLONG #LABEL ; BUFFER ADDRESS 
WRITESTRING 
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Input Long Word Pointer to ASCII string 

sp—> 


Hie character string with a length specified by the first byte in the string is 
combined with the error output global masks, and is then written to the text 
device specified as the error output device. 

Example: 

FUSHLONG #LABEL ; BUFFER ADDRESS 
ERRWRTTESTRING 


WriteBlock Function number $1E 


Input LongWord Pointer to ASCII text 

Input Word Offset 

Input Word Count 

sp—> 

The character string with a length specified by the Count at the memory 
location Pointer+Offset is combined with the output global masks, and is 
then written to the text device specified as the output device. 


Example: 

FUSHLONG #LABEL 
PEA $0005 

PEA $0008 

WRITEBLOCK 


BUFFER ADDRESS 
START AT 5TH CHAR 
SEND 8 CHARACTERS 


ErrWriteBlock Function number ■ $ IF 


Input 

Input 

Input 

sp—> 


LongWord Pointer to ASCII text 

Word Offset 

Word Count 


The character string with a length specified by the Count at the memory 
location Pointer+OfTset is combined with the error output global masks, 
and is then written to the text device specified as the error output device. 


Example: 

FUSHLONG #LABEL 
PEA $0005 

PEA $0008 

ERRWRITEBLOCK 


SUITER ADDRESS 
START AT 5TH CHAR 
SEND 8 CHARACTERS 


R. Montagne 


4 CONFIDENTIAL 4 


Page 14 





Cortland Text Tool Set 


June 26,1986 


WriteCStting Function number = $20 

Input LongWord Pointer to ASCII C-String 

sp—.> 

The character string terminating with the byte value of $00 is combined with 
the output global masks, and is then written to the text device specified as 
the output device. 

Example: 

FUSHLONG #LABBL ; BUFFO. ADDRESS 
WWTECSTRING 


ErrWriteCString Function number ■ $21 

Input LongWord Pointer to ASCII C-Stiing 

sp—> 

The character smng terminating with the byte value of $00 is combined with 
the error output global masks, and is then written to the text device specified 
as the error output device. 

Example: 

FUSHLONG #LABEL ; BUFFER ADDRESS 
ERRWRITECSTRING 
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ReadChar 

Function number = $22 

Input 

Word 

Space for result 

Input 

Word 

Echo Flag 

Sp^“> 



Output 

sp—> 

Word 

Character (in low byte) 


The character read from the text device that has been set as the input device 
is combined with the input global masks and returned on the stack. If the 
ECHO flag is set to a value of $0001, then the character read from the input 
device will be written to the output device. If the ECHO flag is set to zero, 
that the character will not be written to the output device. 

Example: 

PEA $0000 ; SPACE FOR RESULT 

PEA $0000 ; BONT ECHO 

READCHAR 


ReadBlock 

Input 

Input 

Input 

Input 

sp—> 


Function number - $23 

LongWord Pointer 
Word Offset 

Word BlockSize 

Word Echo Flag 


The block of characters of the size specified by BlockSize is read from the 
text device that has been set as the input device, and is combined with the 
input global masks before being written to the memory location specified by 
Pointer+Offset. If the ECHO flag is set to a value of $0001, then the 
character read from the input device will be written to the output device. If 
the ECHO flag is set to zero, then the character will not be written to the 
output device. 


Example: 

PUSHLONG #LABEL 
PEA $0005 

PEA $0008 

PEA $0001 

READBLOCK 


BUFFER ADDRESS 
START AT 5TH CHAR. 
READ 8 CHARACTERS 
ECHO CHARACTERS 
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Headline Function number « $24 


Input 

Word 

Space for result 

Input 

Long Word 

BufTerPointer 

Input 

Word 

MaxCount (maximum line length) 

Input 

Word 

EOL (end of line character in low byte) 

Input 

sp—> 

Word 

Echo Flag 

Output 

sp—> 

Word 

Count of characters received. 


The character string is read from the text device that has been set as the input 
device, and is combined with the input global masks before being written to 
the memory location specified by BufTerPointer. The character string is 
terminated by an EOL character, or if the count of characters received is 
equal to tire maximum line length specified by MaxCount. The count of 
characters received is returned on the stack. If the ECHO flag is set to a 
value of $0001, then the character read from the input device win be written 
to the output device. If the ECHO flag is set to zero, then the character will 
not be written to the output device. 


Example: 

FEA $0000 

FUSHLQNG #LABEL 
PEA $000A 

PEA SGOOD 

PEA $0001 

READLINE 


; S PACE F OR RESULT 
; BUFFER ADDRESS 
; READ 10 CHARACTERS 
;EOL**CR 

; ECHO CHARACTERS 
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RAM based device drivers must support five entry points. These are INIT, 
READ, WRITE, STATUS and CONTROL. Ram based drivers may be located at 
any address and in any bank. Enfry points must be supported by the RAM based 
driver as follows: 


RAMDRIVER Base Address 
RAMDRIVER Base Address-*-3 
RAMDRIVER Base Address*^ 
RAMDRIVER Base Address+9 
RAMDRIVER Base Address* 12 


Ini tializa tion entry point 
Read entry point 
Write witty point 
Status entry point 
Control entry point 


Ram based drivers will be called in 65116 native mode with 16 bit v m' and Y. 
Ram based drivers should return to the text tool set via an RTL' instruction. Data 
or ascii characters are passed to the ram based driver from the text tool set via die 
low byte of the sixteen bit accumulator. Data or ascii characters are passed to the 
text tools set from the ram based driver via the low byte of the sixteen bit 
accumulator. Ram based driven should make no assumption about the state of die 
data bank register or the direct page register. I/O performed by ram basal drivers 
should operate on a single character basis. All functions within the text tools set 
which interface to different string types will Ire supported by the tool set and not 
the device. 
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Summary of functions within the Text Tool Set: 


Function Number 

Function Description 

$01 

1 

TextBootlnit 

$02 

2 

TextS tartUp 

$03 

3 

TextShutDown 

$04 

4 

TextVereion 

$05 

5 

TextReset 

$06 

6 

TextS tatus 

$07 

7 

TextSparcl 

$08 

8 

TextSpare2 

$09 

9 

SetlnGlobals 

$0A 

10 

SetOutGlobals 

SOB 

11 

SetErrGlobals 

$0C 

12 

GetlnGlobals 

SOD 

13 

GetOutGlobals 

$0E 

14 

GetEnGlobals 

$0F 

15 

SetlnputDevice 

$10 

16 

SetOutputDevice 

$11 

17 

SetEnoiDevice 

$12 

18 

GetlnputDevice 

$13 

19 

GetOutputDevice 

$14 

20 

GetErrorDevice 

$15 

21 

InitTextDev 

$16 

22 

QriTextDev 

$17 

23 

StatusTextDev 

$18 

24 

WriteChar 

$19 

25 

EnWriteChar 

$1A 

26 

WriteUne 

$1B 

27 

ErrWriteline 

$1C 

28 

WriteString 

SID 

29 

En-WriteString 

$1E 

30 

WriteBlock 

$1F 

31 

EsrWriteBlock 

$20 

32 

WriteCString 

$21 

33 

EsrWriteCS&ing 

$22 

34 

ReadChar 

$23 

35 

ReadBlock 

$24 

36 

ReadLim 
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